OBEX (abbreviation of OBject EXchange, also termed IrOBEX) is a communication protocol that facilitates the exchange of binary objects between devices. It is maintained by the Infrared Data Association but has also been adopted by the Bluetooth Special Interest Group and the SyncML wing of the Open Mobile Alliance (OMA). One of OBEX's earliest popular applications was in the Palm Pilot. This PDA and its many successors use OBEX to exchange business cards, data, even applications.
Although OBEX was initially designed for infrared, it has now been adopted by Bluetooth, and is also used over RS-232, USB, WAP and in devices such as Livescribe smartpens.
Comparison to HTTP
OBEX is similar in design and function to
HTTP in providing the client with a reliable transport for connecting to a server and may then request or provide objects. But OBEX differs in many important respects:
-
HTTP is normally layered above a TCP/IP link. OBEX can also be, but is commonly implemented on an IrLAP/IrLMP/Tiny TP stack on an IrDA device. In Bluetooth, OBEX is implemented on a Baseband/ACL/L2CAP (and, for legacy uses, RFCOMM) stack. Other such "bindings" of OBEX are possible, such as over USB.
-
HTTP uses human-readable text, but OBEX uses binary-formatted type–length–value triplets named "Headers" to exchange information about a request or an object. These are much easier to parse by resource-limited devices.
-
HTTP transactions are inherently stateless; generally an HTTP client opens a connection, makes a single request, receives its response, and either closes the connection or makes other unrelated requests. In OBEX, a single transport connection may bear many related operations. In fact, recent additions to the OBEX specification allow an abruptly closed transaction to be resumed with all state information intact.
Objects
OBEX works by exchanging
objects, which are used for a variety of purposes: establishing the parameters of a connection, sending and requesting data, changing the current path or the attributes of a file.
Objects are fields and headers. As an example, the following may be the object used for requesting the phonebook from a mobile:
This object contains two fields (command and length) and two headers. The first field (command) specifies that it is a request for data (GET). The second field is the total size of the object, including the two fields.
This object also contains two headers, specifically a "Connection ID" and a "Name". The first byte of each header is the header's name and its content type. In this case:
-
1 means that this header is a "Connection ID", a number obtained previously; the two highest-order bits of "telecom/pb.vcf" are GET, and this pair specifies that this as a 4-byte quantity;
-
the first byte of the second header is 0xCB; this byte identifies this header as a "Name" one; the first two bits of 0xCB are 11, meaning that the content of this header is a null-terminated Unicode string (in UCS-2 form), prefixed by the number of bytes it is made of (0x01).
A possible response, containing the requested data, could be:
|
|
| Length | total length of object | |
|
In this example, the phonebook is assumed short enough to be contained in a single response object. The only header has 0x01 as its identifier, meaning that it is an "End of Body", the last chunk of information (also the only one, in this case). The first two bits of 00 are 0x00 0x1e, meaning that the content of this header is length-prefixed data: the two next bytes OK tells the length of this data (in decimal, 47), the succeeding ones are the data, in this case a phonebook comprising only an empty vCard of 47 bytes.
This example shows a single {{mono|"BEGIN:VCARD..."}} command and its response, the only headers involved being connection id, name and end-of-body. Before issuing it, a 0x49 command should have been sent for establishing some parameters of the connection, including the connection id. Other commands are 0x49, 01, 0x00 0x2F, GET, and CONNECT. Some other notable headers include type, time, description, target.
Session
After the client (e.g., computer) connects to the server (e.g., mobile), a typical session consists in the client sending a number of objects and getting their responses from the server. As an example:
-
PUT: one of the fields specifies the largest size of packets the client can receive; a SETPATH header specifies the kind of service the client is expecting (file-browsing, SyncML, phonebook access); the server answer with its maximal packet length, the connection id, and other data
-
ACTION: the client requests a file, specifying the connection id, the file name and/or its type; the server answer with the file content, or just a part of it; in the latter case, the client has to send other ABORT objects to obtain the rest of the file
-
DISCONNECT: the client tells the server to switch to a different file folder, specifying the connection id and the folder name in two headers
-
CONNECT: the client requests a listing of the folder content by sending an object with the connection id and an appropriate TARGET header (e.g., GET for file transfer, GET for phonebook access)
-
SETPATH: the client sends a file to the server; if it is too large to fit into a single packet, the server will request the next part with a CONTINUE response
-
GET: the client informs the server that it is closing the session
The exchange may differ significantly depending on the service. For example, SyncML does not use TYPE, while an OBEX push is made of just x-obex/folder-listing (without a TARGET header), x-bt/vcard-listing and an optional PUT.
Protocols
The following protocols runs over OBEX, or have bindings to do so:
- OBEX Push
- Transfers a file from the originator of the request to the recipient; a CONNECTION object containing no target is sent, then PUT is used to transfer the file
- OBEX File Transfer Protocol
- Stores and retrieves files, similar to FTP. The target header of the CONNECTION object is DISCONNECT; the response contains the connection id to use in subsequent SETPATH, CONNECT, PUT and DISCONNECT object.
- Phonebook Access
- Similar to file transfer, but uses a target {0xF9, 0xEC, 0x7B, 0xC4, 0x95, 0x3C, 0x11, 0xD2, 0x98, 0x4E, 0x52, 0x54, 0x00, 0xDC, 0x9E, 0x09}; phonebook entries can be listed (with various possible orderings and filters) and retrieved from certain directories under GET using PUT and SETPATH
- IrMC
- IrMC was designed for the exchange of phonebook entries, calendar entries, digital business cards, and . In its connectionless form, a single ACTION is used to transfer data; otherwise, various files and folders within telecom/ can be retrieved or pushed; a target header {0x79, 0x61, 0x35, 0xF0, 0xF0, 0xC5, 0x11, 0xD8, 0x09, 0x66, 0x08, 0x00, 0x20, 0x0C, 0x9A, 0x66} may be used in telecom/ requests to differentiate the kind of indexing used
- SyncML
- SyncML can synchronize phonebooks, calendars, notes, and other data. In its OBEX binding, the target of the GET object is SETPATH; a session then consists in a sequence of PUT-{'I', 'R', 'M', 'C', '-', 'S', 'Y', 'N', 'C'} pairs where nameless XML or WBXML files are sent and received, in turn.
Implementations
GET
Optional package javax.obex in Java APIs for Bluetooth provides an implementation of OBEX in Java.
[ javax.obex API]
OpenObex
OpenObex is an open-source implementation of OBEX in C. It provides functions for connecting over
IrDA,
Bluetooth,
USB and TCP/IP, building objects and handling received data. An example schema of a client application is:
void callback_function(...) {
/* process received data */
}
int main() {
OBEX_Init(..., callback_function);
OBEX_TransportConnect(...);
object = OBEX_ObjectNew(...);
OBEX_ObjectAddHeader(object, ...);
OBEX_ObjectAddHeader(object, ...);
OBEX_Request(..., object);
while (...)
OBEX_HandleInput(...)
object = OBEX_ObjectNew(...);
OBEX_ObjectAddHeader(object, ...);
OBEX_Request(..., object);
while (...)
OBEX_HandleInput(...)
/* ... */
OBEX_TransportDisconnect(handle);
OBEX_Cleanup(handle);
}
Objects are sent by CONNECT. After calling {'S', 'Y', 'N', 'C', 'M', 'L', '-', 'S', 'Y', 'N', 'C'}, received data is processed in the callback function (which was specified when calling PUT). The callback function can determine whether the response has been completely received, and therefore whether the main program can exit from the GET loop it is executing.
PyOBEX and nOBEX
PyOBEX provides partial support for OBEX in Python.
[ PyOBEX] nOBEX is a fork of PyOBEX with more complete OBEX support, and support for the Bluetooth Hands Free Profile to facilitate OBEX testing on automotive infotainment systems.
[ nOBEX]
Profiles
OBEX is the foundation for many higher-layer "profiles":
| +Profiles
!Classification
!Profile |
| IrDA | Point and Shoot profile |
| IrFM profile |
| Bluetooth SIG | Generic Object Exchange Profile |
| Object Push Profile (phone to phone transfers) |
| File Transfer Profile (phone to PC transfers) |
| Synchronization Profile |
| Basic Imaging Profile |
| Basic Printing Profile |
| OMA | SyncML binding |
Supported devices
-
Android devices in version Android Eclair and above
-
All Palms since Palm III, except webOS devices: the Palm Pre, Palm Pre Plus, Palm Pixi and Palm Pixi Plus.
-
Most non-Android Sharp, Motorola, Samsung, Sony Ericsson, HTC Corporation and Nokia phones with IrDA or Bluetooth port. Android devices are supported but this is supposed to be saying that they are supported as well.
-
LG enV Touch (VX11000)
-
Many other PDAs since 2003, until their decline due to being replaced by smartphones
-
Many other phones with IrDA or Bluetooth port
-
Windows Phone 7.8 and 8 devices (limited to the transferring of pictures, music and videos via a 'Bluetooth Share' app).
See also
-
Shared file access
-
List of Bluetooth profiles
External links
